package jblip.resources;

import java.io.Serializable;

/**
 * Resource representing user subscriptions (tracking). 
 * 
 * @author Krzysztof Sroka
 * @since 0.2
 */
public interface Subscription extends Serializable {
  /**
   * Returns login name of the user being tracked.
   * 
   * @return login name of the user being tracked.
   */
  String getTrackedUserName();
  
  /**
   * Returns login name of the tracking user.
   * 
   * @return login name of the tracking user.
   */
  String getTrackingUserName();
  
  /**
   * Returns resource representing detailed info on the user being tracked.
   * 
   * <p><i>NOTE: This resource is optional and its availability depends on
   * details of a Blip client's request. In case this resource is unavailable,
   * this method returns <code>null</code>.</i></p>
   * 
   * @return resource representing detailed info on the user being tracked.
   */
  User getTrackedUser();
  
  /**
   * Returns resource representing detailed info on the tracking user.
   * 
   * <p><i>NOTE: This resource is optional and its availability depends on
   * details of a Blip client's request. In case this resource is unavailable,
   * this method returns <code>null</code>.</i></p>
   * 
   * @return resource representing detailed info on the tracking user.
   */
  User getTrackingUser();
  
  /**
   * Returns transport by which this subscription is tracked.
   * 
   * <p>The only available transports as of API 0.02 are 
   * <code>Transport.WWW</code>, <code>Transport.JABBER</code> and
   * <code>Transport.GADUGADU</code>.</p>
   * 
   * @return transport by which this subscription is tracked.
   */
  Transport getTransport();
}
